ODClipboard

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODClipboard

Superclasses
ODObject
Subclasses
none

An object of the ODClipboard class provides data-transfer services between OpenDoc documents and their parts and between OpenDoc and non-OpenDoc documents.

Description
On each platform, OpenDoc provides an implementation of the ODClipboard class that gives a common, platform-independent clipboard interface for all parts. Each such implementation of ODClipboard provides access to a platform-specific clipboard (also known as the system clipboard) via OpenDoc storage units. This approach not only shields part editors from the underlying system clipboard mechanism, it also allows for more complex data transfers between different parts and documents, including linking.
When a document is opened, the session object creates a single clipboard object. All parts of that document share the clipboard object; you can obtain a reference to it by calling the session object's GetClipboard method (page 606). You must not cache this object; instead, you must call the session object's GetClipboard method whenever you need the clipboard object.
Parts typically invoke ODClipboard methods in response to Edit menu commands such as Copy, Cut, Paste, and Paste As and during certain linking and drag-and-drop operations. In addition to the traditional data-transfer features associated with these commands, OpenDoc's ability to clone objects allows a data-transfer operation to involve not only intrinsic content of the source part, but also the content of embedded parts, which may be of any part kind and embedded to any depth. The OpenDoc clipboard mechanism also allows more flexibility in how items are pasted. For example, the transferred data can be embedded or incorporated into the destination part with optional translations.
You should access the clipboard only when your part is running in the frontmost process and your part owns the clipboard focus. You can acquire the clipboard focus by calling the arbitrator object's RequestFocus method (page 53). Acquiring the clipboard focus ensures that no other part can access or modify the data while your transfers are taking place. An active part must therefore acquire the clipboard focus before enabling the appropriate commands in the Edit menu. The recommended strategy is to acquire focus in your part's AdjustMenus method (page 480) and to relinquish focus in your part's HandleEvent method (page 526).
Once your part has the clipboard focus, you can write data to, or read data from, the clipboard. If you are writing data to the clipboard, you must first call the Clear method (page 89) of the clipboard object. Data transfers requested by any part operate on the clipboard object's content storage unit. You obtain a reference to that storage unit by calling the clipboard's GetContentStorageUnit method (page 92). The content storage unit contains the data most recently cut or copied to the clipboard. You must not cache that storage unit; instead you must call the GetContentStorageUnit method whenever you need to access the storage unit.
To transfer persistent objects to or from the clipboard, you must clone them using the cloning methods of their draft object. Additional methods of ODClipboard transfer data between the system clipboard and the clipboard object's storage unit.
For efficient transfer of large amounts of data to and from the clipboard, OpenDoc supports promises. The source part can delay a data transfer by writing a promise to the clipboard. If, and only if, a destination subsequently seeks to retrieve the data, the source part fulfills its promise by writing the data to the clipboard. This time-saving technique is transparent to the destination part.
The GetUpdateID method (page 93) of the clipboard object returns an update ID that uniquely identifies the current generation or version of the clipboard. You can save this update ID and use it to detect subsequent changes in the clipboard content.
Parts that support Cut and Paste must support undo of those operations. If the user moves objects from one part to another and then undoes the move, the objects must be reinstated at the source. This can happen only if the part initiating the cut and the part performing the paste both support undo. Your part should notify the clipboard object whenever a Cut, Copy, or Paste operation is done, undone, or redone by calling the clipboard object's ActionDone (page 86), ActionUndone (page 88), or ActionRedone (page 87) methods, respectively.
For more information about cloning, promises, and using the clipboard object, see the chapter on data transfer in the OpenDoc Programmer's Guide for the MacOS. For more information on cloning methods, see the descriptions of the classes ODDraft (page 147) and ODPart (page 459). For information on undoing and redoing actions, see the chapter on windows and menus in the OpenDoc Programmer's Guide for the MacOS and the ODUndo class description (page 806). For information on using a link specification to indicate that the source part can create a link, see the ODLinkSpec class description (page 390).

Methods
This section presents summary descriptions of the ODClipboard methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [D] are called only by the document shell or container applications. Methods marked [M] are specific to the Mac OS platform.
Accessing

Clear
Immediately removes all the data stored in this clipboard object.
GetContentStorageUnit
Returns a reference to the storage unit containing this clipboard object's current content.
Update Control

ExportClipboard [D]
Updates the system clipboard if this clipboard object has been changed since the last update of the system clipboard.
DraftClosing [D]
Notifies this clipboard object that the specified draft is about to be closed or reverted.
DraftSaved [D]
Notifies this clipboard object that the specified draft has been saved.
GetUpdateID
Returns an update ID identifying the current generation or version of this clipboard object.
SetPlatformClipboard
Copies any data of the specified types from this clipboard object to the system clipboard if this clipboard object has changed since the last update to the system clipboard.
Dialog Control

ShowPasteAsDialog [M]
Displays the Paste As dialog box and sets the appropriate dialog items according to the input parameters.
Undoing Clipboard Operations

ActionDone
Notifies this clipboard object that a Cut, Copy, or Paste action was done.
ActionUndone
Notifies this clipboard object that a Cut, Copy, or Paste action was undone.
ActionRedone
Notifies this clipboard object that a Cut, Copy, or Paste action was redone.

Methods
ActionDone
ActionRedone
ActionUndone
Clear
DraftClosing
DraftSaved
ExportClipboard
GetContentStorageUnit
GetUpdateID
SetPlatformClipboard
ShowPasteAsDialog